GSTIN Details Retrieval API

The following document highlights the details of the GSTIN Details Retrieval API.

API Description

Objective

The GSTIN Details Retrieval API queries the GSTIN portal and returns a GSTIN's registration status, taxpayer details, and financial activity data, including filing history, tax liability, and HSN information.

Input	Output
The GSTIN and flags indicating which details are required	The registration details, HSN data, branch details, and filing history associated with the GSTIN. A complete list of fields is provided under the Success Response Details section.

API URL

https://ind-engine.thomas.hyperverge.co/v1/GSTINDetailsRetrieval

API Endpoint

GSTINDetailsRetrieval

Overview

The GSTIN Details Retrieval API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the GSTIN Details Retrieval API.

Headers

Parameter	Mandatory or Optional	Description	Input Format
content-type	Mandatory	The media type for the request payload.	application/json
appId	Mandatory	The application identifier from HyperVerge. You can find the details in the dashboard's credentials tab.	Unique value
appKey	Mandatory	The application key from HyperVerge. You can find the details in the dashboard's credentials tab.	Unique value
transactionId	Mandatory	A unique identifier for tracking a user journey.	Unique value mapped to the user's journey

Inputs

The following table provides the complete information on the parameters used in the request body for the GSTIN Details Retrieval API:

Parameter	Mandatory or Optional	Type	Description	Input Format	Default Value
gstin	Mandatory	String	The Goods and Services Tax Identification Number (GSTIN) of the user.	15-character alphanumeric string	Not Applicable
hsnDetails	Mandatory	String	Indicates whether HSN (Harmonized System of Nomenclature) details are required in the response.	true or false	Not Applicable
branchDetails	Mandatory	String	Indicates whether branch details are required in the response.	true or false	Not Applicable
filingDetails	Mandatory	String	Indicates whether filing details are required in the response.	true or false	Not Applicable
liabilityPaidDetails	Mandatory	String	Indicates whether liability paid details are required in the response.	true or false	Not Applicable

Request

The following section shows the standard curl request for the GSTIN Details Retrieval API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/GSTINDetailsRetrieval' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
    "gstin": "<Enter_the_GSTIN>",
    "hsnDetails": "<Enter_true_or_false>",
    "branchDetails": "<Enter_true_or_false>",
    "filingDetails": "<Enter_true_or_false>",
    "liabilityPaidDetails": "<Enter_true_or_false>"
}'

Success Response

The following is a sample response from the GSTIN Details Retrieval API when all detail flags are set to true:

Flags set to True

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "basicDetails": {
      "gstin": "<GSTIN>",
      "ekycFlag": "<eKYC_Flag>",
      "compositionRate": "<Composition_Rate>",
      "percentTaxInCash": "<Percent_Tax_In_Cash>",
      "aggreTurnOverFY": "<Aggregate_Turnover_Financial_Year>",
      "registrationType": "<Registration_Type>",
      "aggreTurnOver": "<Aggregate_Turnover>",
      "businessNature": [
        "<Business_Nature_1>",
        "<Business_Nature_2>"
      ],
      "registrationDate": "<Registration_Date>",
      "registrationStatus": "<Registration_Status>",
      "percentTaxInCashFY": "<Percent_Tax_In_Cash_FY>",
      "memberDetails": [
        "<Member_1>",
        "<Member_2>"
      ],
      "natureOfCoreBusinessActivity": "<Nature_Of_Core_Business_Activity>",
      "aadhaarVerified": "<Aadhaar_Verified>",
      "legalBusinessName": "<Legal_Business_Name>",
      "constitutionOfBusiness": "<Constitution_Of_Business>",
      "tradeName": "<Trade_Name>",
      "centralJurisdiction": "<Central_Jurisdiction>",
      "isEInvoiceMandated": "<Is_E_Invoice_Mandated>",
      "stateJurisdiction": "<State_Jurisdiction>",
      "cancellationDate": "<Cancellation_Date>",
      "isEInvoiceOpted": "<Is_E_Invoice_Opted>"
    },
    "hsnDetails": {
      "goods": null,
      "services": [
        {
          "hsnCode": "<HSN_Code>",
          "hsnDescription": "<HSN_Description>"
        }
      ]
    },
    "branchDetails": {
      "message": "<Message>",
      "principalAddress": {
        "address": "<Principal_Address>",
        "natureOfBusiness": "<Nature_Of_Business>"
      },
      "additionalAddresses": []
    },
    "filingDetails": {
      "filingStatus": [
        [
          {
            "finYear": "<Financial_Year>",
            "returnType": "<Return_Type>",
            "returnPeriod": "<Return_Period>",
            "modeOfFiling": "<Mode_Of_Filing>",
            "dateOfFiling": "<Date_Of_Filing>"
          }
        ]
      ]
    }
  }
}

Success Response Details

The following table provides the details of the fields in a success response:

Parameter	Type	Description
basicDetails.gstin	String	The GSTIN provided in the request.
basicDetails.legalBusinessName	String	The legal name of the business as registered on the GSTIN portal.
basicDetails.tradeName	String	The trade name of the business.
basicDetails.registrationStatus	String	The current registration status of the GSTIN, such as "Active" or "Cancelled".
basicDetails.registrationDate	String	The date on which the GSTIN was registered (DD/MM/YYYY).
basicDetails.cancellationDate	String	The date on which the GSTIN was cancelled, if applicable.
basicDetails.registrationType	String	The type of GST registration, such as "Regular" or "Composition".
basicDetails.constitutionOfBusiness	String	The legal constitution of the business, such as "Private Limited Company" or "Partnership".
basicDetails.businessNature	Array	The nature of business activities associated with the GSTIN.
basicDetails.natureOfCoreBusinessActivity	String	The primary business activity of the entity.
basicDetails.centralJurisdiction	String	The central tax jurisdiction under which the GSTIN is registered.
basicDetails.stateJurisdiction	String	The state tax jurisdiction under which the GSTIN is registered.
basicDetails.aggreTurnOver	String	The aggregate turnover of the entity.
basicDetails.aggreTurnOverFY	String	The financial year corresponding to the aggregate turnover.
basicDetails.isEInvoiceMandated	String	Indicates whether e-invoicing is mandated for the entity.
basicDetails.isEInvoiceOpted	String	Indicates whether the entity has opted into e-invoicing.
basicDetails.aadhaarVerified	String	Indicates whether the Aadhaar of the business owner has been verified.
basicDetails.ekycFlag	String	The eKYC status of the entity.
basicDetails.memberDetails	Array	The list of members associated with the entity.
hsnDetails.goods	Array / null	The HSN codes and descriptions for goods traded by the entity. Returns null if no goods are registered. Returned only when hsnDetails is set to "true".
hsnDetails.services	Array	The HSN codes and descriptions for services provided by the entity. Returned only when hsnDetails is set to "true".
branchDetails.principalAddress	Object	The principal place of business address and its nature of business. Returned only when branchDetails is set to "true".
branchDetails.additionalAddresses	Array	The list of additional business addresses. Returned only when branchDetails is set to "true".
filingDetails.filingStatus	Array	The GST return filing history, including financial year, return type, return period, mode of filing, and date of filing. Returned only when filingDetails is set to "true".

Failure Response

The following is a sample response when the provided GSTIN is invalid or does not exist:

{
  "statusCode": 400,
  "status": "failure",
  "error": "<Error_Message>",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Responses

The following are some error responses from the GSTIN Details Retrieval API:

Missing/Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

An error response from the GSTIN Details Retrieval API contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values.	Verify and provide valid credentials from the dashboard's credentials tab.
500	Internal Server Error	An unexpected error occurred on the server.	Check the request headers or contact the HyperVerge team for resolution.